Open
Conversation
Contributor
WalkthroughThis pull request adds a new blog post about CNAME flattening for Appwrite Sites, along with a corresponding cache entry. The blog post provides technical documentation covering DNS/CNAME concepts, background on apex domain handling through various DNS record types (CNAME, ALIAS, ANAME), details on Appwrite Sites' CNAME flattening implementation, TTL recommendations, and step-by-step guidance for connecting custom domains without transferring DNS control. A single image asset entry was added to the optimization cache manifest to track the blog post's cover image. Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc:
- Line 111: Update the sentence "Once the DNS propagates, your site will be
available on your custom domain with SSL automatically configured." to include a
short caveat about CAA records: note that domains with restrictive CAA records
must authorize Appwrite Sites' CA (Certainly / certainly.com) before TLS can be
issued, and add a link to the docs for CAA configuration; mention the
recommended CAA value (0 issue "certainly.com") for CNAME-flattened Sites to
ensure certificate issuance succeeds.
- Around line 66-68: Update the paragraph about CNAME/CNAME-flattening to
correct DNS semantics: state that apex (flattening) implementations synthesize
A/AAAA records rather than creating an RFC‑compliant CNAME, clarify that the
restriction is that a name with a CNAME RRset cannot have other data at that
same owner name (not that multiple RRsets cannot share an owner name), and
change the final sentence to distinguish CNAME chains (a sequence of CNAMEs)
from cycles/loops and warn to avoid cycles; replace the existing sentences
referencing "CNAME flattening" and "CNAME looping" accordingly.
- Line 92: Update the TTL guidance paragraph so it is less absolute: state that
provider defaults vary and that lowering TTL does not speed DNS resolution but
reduces cache lifetime, increasing query load; recommend using a short TTL
(e.g., 5 minutes) only temporarily for debugging or during planned changes, then
restore a more typical value afterward, and call out the trade-offs (more
queries vs. faster propagation of updates) in place of the current definitive
wording about resolution time.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: c49c99dd-84fa-40c0-b187-f28db78dfcf6
⛔ Files ignored due to path filters (1)
static/images/blog/cname-flattening-for-appwrite-sites/cover.pngis excluded by!**/*.png
📒 Files selected for processing (2)
.optimize-cache.jsonsrc/routes/blog/post/cname-flattening-for-appwrite-sites/+page.markdoc
Comment on lines
+66
to
+68
| In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs. | ||
|
|
||
| When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies. |
Contributor
There was a problem hiding this comment.
This paragraph misstates the DNS rules.
Apex flattening does not make a literal apex CNAME RFC-compliant; the provider synthesizes A/AAAA answers instead. Also, multiple RRsets can share the same owner name—the restriction is specifically that a name with a CNAME cannot have other data at that same name. The last sentence also describes a chain, not a loop/cycle.
Suggested rewording
-In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs.
-
-When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies.
+In practice, CNAME flattening gives you CNAME-like behavior at the root without publishing a literal apex CNAME in DNS responses. The DNS provider resolves the target internally and serves synthesized A/AAAA answers instead.
+
+When a DNS lookup follows a CNAME, the resolver continues resolution using the canonical target name and returns the final answer to the client. CNAMEs can add another lookup step, though the latency impact is usually small. A name that has a CNAME must not also have other record types at that same name, and CNAME cycles (for example, `a.example` -> `b.example` -> `a.example`) should be avoided.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs. | |
| When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies. | |
| In practice, CNAME flattening gives you CNAME-like behavior at the root without publishing a literal apex CNAME in DNS responses. The DNS provider resolves the target internally and serves synthesized A/AAAA answers instead. | |
| When a DNS lookup follows a CNAME, the resolver continues resolution using the canonical target name and returns the final answer to the client. CNAMEs can add another lookup step, though the latency impact is usually small. A name that has a CNAME must not also have other record types at that same name, and CNAME cycles (for example, `a.example` -> `b.example` -> `a.example`) should be avoided. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc
around lines 66 - 68, Update the paragraph about CNAME/CNAME-flattening to
correct DNS semantics: state that apex (flattening) implementations synthesize
A/AAAA records rather than creating an RFC‑compliant CNAME, clarify that the
restriction is that a name with a CNAME RRset cannot have other data at that
same owner name (not that multiple RRsets cannot share an owner name), and
change the final sentence to distinguish CNAME chains (a sequence of CNAMEs)
from cycles/loops and warn to avoid cycles; replace the existing sentences
referencing "CNAME flattening" and "CNAME looping" accordingly.
Contributor
There was a problem hiding this comment.
Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!
| 3. Verify the domain in Appwrite. | ||
| 4. Go live. | ||
|
|
||
| When creating the DNS record, note that the default TTL (Time To Live) is often set to 24 hours unless overridden. It is recommended to set the TTL to 5 minutes for quick propagation. A lower TTL allows DNS changes to propagate faster across DNS servers, which improves resolution time and ensures updates take effect more quickly. DNS servers and resolvers use cache to temporarily store DNS answers, which can affect how quickly changes to CNAME records take effect. |
Contributor
There was a problem hiding this comment.
The TTL guidance is too absolute and partly inaccurate.
Provider defaults vary, and a lower TTL does not improve resolution time—it only shortens how long stale answers may stay cached, usually at the cost of more DNS queries. Framing 5 minutes as a temporary setup/debugging value would be safer.
Suggested rewording
-When creating the DNS record, note that the default TTL (Time To Live) is often set to 24 hours unless overridden. It is recommended to set the TTL to 5 minutes for quick propagation. A lower TTL allows DNS changes to propagate faster across DNS servers, which improves resolution time and ensures updates take effect more quickly. DNS servers and resolvers use cache to temporarily store DNS answers, which can affect how quickly changes to CNAME records take effect.
+When creating the DNS record, use your provider's default TTL unless you expect to change the record again soon. During initial setup or troubleshooting, a shorter TTL such as 5 minutes can reduce how long older DNS answers remain cached. DNS servers and resolvers cache answers, so TTL directly affects how quickly record changes are observed.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| When creating the DNS record, note that the default TTL (Time To Live) is often set to 24 hours unless overridden. It is recommended to set the TTL to 5 minutes for quick propagation. A lower TTL allows DNS changes to propagate faster across DNS servers, which improves resolution time and ensures updates take effect more quickly. DNS servers and resolvers use cache to temporarily store DNS answers, which can affect how quickly changes to CNAME records take effect. | |
| When creating the DNS record, use your provider's default TTL unless you expect to change the record again soon. During initial setup or troubleshooting, a shorter TTL such as 5 minutes can reduce how long older DNS answers remain cached. DNS servers and resolvers cache answers, so TTL directly affects how quickly record changes are observed. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc at
line 92, Update the TTL guidance paragraph so it is less absolute: state that
provider defaults vary and that lowering TTL does not speed DNS resolution but
reduces cache lifetime, increasing query load; recommend using a short TTL
(e.g., 5 minutes) only temporarily for debugging or during planned changes, then
restore a more typical value afterward, and call out the trade-offs (more
queries vs. faster propagation of updates) in place of the current definitive
wording about resolution time.
| 5. Create the required DNS record directly, using the correct record type (CNAME or ANAME). | ||
| 6. Return to Appwrite and verify the domain. | ||
|
|
||
| Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. |
Contributor
There was a problem hiding this comment.
Add the CAA caveat before promising automatic SSL.
This is true for most setups, but domains with restrictive CAA records still need to authorize Appwrite Sites' CA or certificate issuance can stall. A short note or docs link here would prevent a confusing failure mode for that subset of users.
Suggested change
-Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured.
+Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. If your domain already uses restrictive CAA records, make sure they allow `certainly.com` so certificate issuance can complete.Based on learnings, Appwrite Cloud Sites uses Certainly (Fastly's CA) for TLS certificates, not Let's Encrypt. The CAA record value 0 issue "certainly.com" is correct for Sites with CNAME flattening.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. | |
| Once the DNS propagates, your site will be available on your custom domain with SSL automatically configured. If your domain already uses restrictive CAA records, make sure they allow `certainly.com` so certificate issuance can complete. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/routes/blog/post/cname-flattening-for-appwrite-sites/`+page.markdoc at
line 111, Update the sentence "Once the DNS propagates, your site will be
available on your custom domain with SSL automatically configured." to include a
short caveat about CAA records: note that domains with restrictive CAA records
must authorize Appwrite Sites' CA (Certainly / certainly.com) before TLS can be
issued, and add a link to the docs for CAA configuration; mention the
recommended CAA value (0 issue "certainly.com") for CNAME-flattened Sites to
ensure certificate issuance succeeds.
adityaoberai
requested changes
Mar 13, 2026
Comment on lines
+39
to
+40
| - Email and other subdomain configurations | ||
| - Mail (handled by MX records, which direct email to the correct mail server) |
Member
There was a problem hiding this comment.
The first email mention needs to be clarified is email forwarding, or it doesn't make sense
|
|
||
| # What is CNAME flattening? | ||
|
|
||
| CNAME flattening is a DNS feature that allows a domain's apex (root domain) to behave like a CNAME, even though standard DNS rules normally prohibit CNAME records at the root. Instead of returning the CNAME itself, the DNS provider resolves the target internally and returns the corresponding IP addresses (A/AAAA records) to the client. This process is called CNAME flattening and is especially useful for handling DNS at the zone apex, where traditional CNAME records are not allowed. |
Member
There was a problem hiding this comment.
Suggested change
| CNAME flattening is a DNS feature that allows a domain's apex (root domain) to behave like a CNAME, even though standard DNS rules normally prohibit CNAME records at the root. Instead of returning the CNAME itself, the DNS provider resolves the target internally and returns the corresponding IP addresses (A/AAAA records) to the client. This process is called CNAME flattening and is especially useful for handling DNS at the zone apex, where traditional CNAME records are not allowed. | |
| CNAME flattening is a feature offered by certain DNS providers that allows a domain's apex (root domain) to behave like a CNAME, even though standard DNS rules normally prohibit CNAME records at the root. Instead of returning the CNAME itself, the DNS provider resolves the target internally and returns the corresponding IP addresses (A/AAAA records) to the client. |
Unnecessary
Comment on lines
+50
to
+56
| Traditionally: | ||
|
|
||
| - **CNAME records** are used to point one domain to another; specifically, a CNAME record maps a hostname (such as a fully qualified domain name) to a canonical name (the true or canonical domain). For example, you might have a CNAME record for `foo.example.com` pointing to `bar.example.net`. | ||
| - But they're not allowed at the root domain (like `example.com`), as per DNS specification and RFC standards (see RFC 1034, RFC 2181). Using a CNAME record at the root is considered bad practice and is technically disallowed. | ||
| - Only subdomains (like `subdomain.example.com`) could use CNAME. | ||
|
|
||
| CNAME records must always point to another domain name, never directly to an IP address. A CNAME points DNS lookups to the target domain, and multiple domains or subdomains can resolve to the same IP address through CNAME records and server configuration. |
Member
There was a problem hiding this comment.
This is excessive information, not sure how necessary it is after the initial paragraph
|
|
||
| Setting up a custom domain should be simple. Add a record, wait a bit, and your site is live. This process involves a DNS lookup, where the fully qualified domain name (FQDN) is resolved to an IP address. | ||
|
|
||
| But in practice, DNS can get complicated, especially when different tools expect you to manage nameservers in different places. DNS records are managed by DNS servers as part of the domain name system, which maps domain names to IP addresses and handles various record types like CNAME, A, and others. We've heard this feedback from many developers using Appwrite Sites, and we've made an improvement to make the process smoother. |
Member
There was a problem hiding this comment.
Suggested change
| But in practice, DNS can get complicated, especially when different tools expect you to manage nameservers in different places. DNS records are managed by DNS servers as part of the domain name system, which maps domain names to IP addresses and handles various record types like CNAME, A, and others. We've heard this feedback from many developers using Appwrite Sites, and we've made an improvement to make the process smoother. | |
| But in practice, DNS can get complicated, especially when different tools expect you to manage nameservers in different places. We've heard this feedback from many developers using Appwrite Sites, and we've made an improvement to make the process smoother. |
Member
There was a problem hiding this comment.
Also, this paragraph rushes context, doesn't set the tone
We should instead talk about why this was necessary for Appwrite in the first place
| unlisted: true | ||
| --- | ||
|
|
||
| Setting up a custom domain should be simple. Add a record, wait a bit, and your site is live. This process involves a DNS lookup, where the fully qualified domain name (FQDN) is resolved to an IP address. |
Member
There was a problem hiding this comment.
Suggested change
| Setting up a custom domain should be simple. Add a record, wait a bit, and your site is live. This process involves a DNS lookup, where the fully qualified domain name (FQDN) is resolved to an IP address. | |
| Setting up a custom domain should be simple. Add a DNS record, wait a bit, and your site is live. |
The line I'm removing is too complex to be a part of the opening paragraph. The opening paragraph should set the tone for the blog, share the story of our problem.
We can shift the nitty gritties to a later section
Comment on lines
+66
to
+68
| In addition, CNAME flattening allows you to create a CNAME record at the root of your domain without violating the RFC's rules. However, CNAME records cannot coexist with other CNAME records or other DNS records (such as MX, TXT, or A) at the same name, except in special cases involving CNAME flattening. Only one DNS record can exist with the same name, and CNAME records must not share the same name with other records, as specified in the RFCs. | ||
|
|
||
| When a DNS lookup occurs on a CNAME record, the DNS resolver performs another DNS lookup on the target domain, restarting the query using the canonical name instead of the original name, and returns the answer to the client. CNAMEs introduce an extra DNS lookup, though this usually causes negligible latency. CNAMEs also facilitate failover by allowing traffic to be redirected to a backup server if the primary one goes down. However, CNAME looping (when a CNAME points to another CNAME) should be avoided to prevent inefficiencies. |
|
|
||
| CNAME records must always point to another domain name, never directly to an IP address. A CNAME points DNS lookups to the target domain, and multiple domains or subdomains can resolve to the same IP address through CNAME records and server configuration. | ||
|
|
||
| # So what does CNAME flattening do? |
Member
There was a problem hiding this comment.
Why can't we explain this entire section simply in the previous one?
|
|
||
| Read the [full CNAME flattening announcement](https://appwrite.io/blog/post/announcing-cname-flattening) for more details. | ||
|
|
||
| # How to connect your domain now |
Member
There was a problem hiding this comment.
Suggested change
| # How to connect your domain now | |
| # How to connect your domain with CNAME flattening |
| 2. Add your custom domain. | ||
| 3. Appwrite will provide a DNS target, which is typically a fully qualified domain name (FQDN) or hostname. | ||
| 4. Go to your DNS provider (Cloudflare, Namecheap, etc.). | ||
| 5. Create the required DNS record directly, using the correct record type (CNAME or ANAME). |
Member
There was a problem hiding this comment.
Suggested change
| 5. Create the required DNS record directly, using the correct record type (CNAME or ANAME). | |
| 5. Create the required CNAME, ANAME, or ALIAS record. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
a new blog about cname flattening for Appwrite sites for SEO purpose
Summary by CodeRabbit
Documentation
Chores